home *** CD-ROM | disk | FTP | other *** search
/ Amiga Magazin: Amiga-CD 1997 September & October / Amiga-CD 1997 #9-10.iso / aminet / gameboyemulator / vgb.doc < prev    next >
Text File  |  1995-10-29  |  14KB  |  322 lines
  1.  
  2.  
  3.                    ******* Virtual GameBoy *******
  4.                 The Portable Nintendo GameBoy Emulator
  5.                              version 0.3
  6.  
  7.                          by Marat Fayzullin
  8.                       
  9.                        email: fms@wam.umd.edu
  10.                             IRC:  RST38h
  11.                WWW:  http://www.cs.umd.edu/users/fms/
  12.  
  13.  
  14.                       Matthias Bethke & Michael Boese
  15.                    http://wwwstud.uni-giessen.de/~s1089/
  16.  
  17. ******* original documentation for the X11 version ********
  18.  
  19.  
  20.          (*) GameBoy is a registered trademark of Nintendo.
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.                           * INTRODUCTION *
  28.  
  29.   Virtual GameBoy [VGB] is a portable emulator of the Nintendo GameBoy 
  30. portable videogame console written in C. Although it is an initial 
  31. release of the emulator in which many things do not quite work yet, it 
  32. was able to run about 85% of 80 games checked with it. You can always
  33. get the latest VGB source code and support files from
  34.  
  35.     http://www.cs.umd.edu/users/fms/GameBoy/VGB.html
  36.  
  37.   There are two different VGB distributions which are both covered by 
  38. this manual:
  39.  
  40. 1. *** Source Code Distribution ***
  41.   This distribution contains C sources of the emulator, and the 
  42. screen/keyboard drivers for Unix/X. Virtual GameBoy has been tested on 
  43. the following Unix systems:
  44.  
  45.   SunOS   Solaris   OSF/1   FreeBSD   HP/UX   Linux   AIX 3.2.5
  46.  
  47.   It was also successfully run on a Mac, Amiga, and Atari Falcon, 
  48. although no decent ports are available for these platforms yet.
  49.   If you would like to write new drivers, or port VGB to another platform, 
  50. *please*, contact me by email or some other means. Feel free to look at 
  51. existing drivers as well as at the other code.
  52.  
  53. 2. *** VGB-Windows Distribution ***
  54.   Due to the flood of requests from the people who use DOS/Windows 
  55. running PCs and are unable to compile the emulator on their own, I have 
  56. ported VGB under Microsoft Windows. This distribution contains an
  57. executable of a limited version of VGB-Windows which doesn't allow you to 
  58. reload a new game from a menu when emulation is already running, and has 
  59. an annoying "Virtual GameBoy DEMO" message across its window. The 
  60. uncrippled version of VGB-Windows is available for $35US from
  61.  
  62.   Marat Fayzullin
  63.   6304 Hampton Place
  64.   Elkridge, MD 21227
  65.   USA
  66.  
  67.   VGB-Windows is a 32-bit application which runs under Windows 3.11, 
  68. Windows 95, and Windows NT. It is compiled with Borland C++ and needs 
  69. Microsoft WinG library which can be obtained from
  70.  
  71.   ftp://ftp.microsoft.com/Softlib/MSFILES/WING10.EXE
  72.  
  73.  
  74.  
  75.  
  76.                       * NEW IN THIS VERSION *
  77.  
  78. o Windows version is made.
  79. o Some heavy magic is done on the interrupts.
  80. o Palette registers are writable now.
  81. o Sprite display routine is changed.
  82. o Sprites are now clipped properly at the top and bottom boundaries.
  83. o -delay/-nodelay option is added.
  84. o etc.
  85.  
  86.  
  87.  
  88.                * SHORT MANUAL FOR THE WINDOWS USERS *
  89.  
  90.   In order to use VGB-Windows, you will first have to install WinG
  91. graphical library which can be obtained from Microsoft [see address
  92. above]. Also, the VGB-WIndows distribution contains a file called
  93. BWCC32.DLL which should be either kept in a directory from which
  94. VGB runs, or copied into \WINDOWS\SYSTEM directory.
  95.   VGB-Windows runs in a resizable window with the following menus:
  96.  
  97. o File
  98.   o New
  99.     This opton allows to run a new game. If you only have an unregistered
  100.     version of VGB-Windows, it will be disabled so that you will only be
  101.     able to choose a game when emulator starts.
  102.   o Setup
  103.     This option pops up a setup dialog allowing to change all 4 GameBoy's
  104.     colors and some emulation parameters:
  105.     o Palette
  106.       Use this group of controls to select a color and change its RGB
  107.       components. The palette controls may not work very well if you
  108.       run Windows in 256-color mode. Use 16-bit or 24-bit graphical
  109.       mode for best effect. 
  110.     o VBlank Period
  111.       This parameter determines how many CPU commands will be executed
  112.       between vertical blanking interrupts. Setting it lower may speed
  113.       up the emulation, but setting it too low will hang it.
  114.     o Update Period
  115.       This parameter determines how many vertical blanking interrupts
  116.       will pass between window refreshes. It is usually set to 2, but
  117.       you can increase it to make VGB work faster. The sprite
  118.       movements become jerky at high update periods though, and some
  119.       sprites may simply disappear.
  120.     o Delay Line Interrupts
  121.       If you see "dirty" horizontal lines in some games, you may turn
  122.       this option on or off to remove them. There is no some universal
  123.       state of this option which will work for all games though.  
  124.   o Quit
  125. o Size
  126.   o 1:1  These options change the window size to be the same as in real
  127.   o 2:1  GameBoy, or 2/3/4 times bigger. Please, note that you can change
  128.   o 3:1  window size by simple dragging the bottom-right corner of a
  129.   o 4:1  window with the mouse.
  130. o Help
  131.   o About
  132.     This option will display a dialog box with copyright information
  133.     and other legal stuff.
  134.  
  135.  
  136.  
  137.                    * FREQUENTLY ASKED QUESTIONS *
  138.  
  139. 1. What is GameBoy?
  140.   GameBoy is a handheld videogame machine produced by Nintendo. It is 
  141. built around a custom CPU similar to Z80, but with some changes. GameBoy 
  142. is frequently laughed at because of its reflective green-on-yellow LCD 
  143. screen which in fact is its virtue. Due to the low power consumption of 
  144. its LCD, GameBoy can work for 35 hours off 4 AA batteries. There is a lot 
  145. of good games produced for GameBoy, both classics [Tetris, Pacman, 
  146. Asteroids, etc.] and specific ones [Final Fantasy series for GB]. It 
  147. excells in RPGs and classic games where gameplay is more important than 
  148. graphics. More information about GameBoy is available from
  149.  
  150.                 http://www.cs.umd.edu/users/fms/GameBoy/
  151.  
  152. 2. Where do I get GameBoy games?
  153.   You buy the cartridges. GameBoy software is copyrighted and still sold. 
  154. Therefore, its distribution is an act of piracy. Nothing prohibits you 
  155. from backing up a cartridge you own and playing it on the emulator though.
  156. To back up a GameBoy cartridge, you can use either SmartCard copier [about
  157. $100 for a standalone version], or a self-built copier, description of
  158. which will hopefully be available at the WWW page soon.
  159.  
  160. 3. Is it legal to spread GameBoy cartridge snapshots?
  161.   NO. Be aware of the fact that by using commercial software you haven't 
  162. bought, you are commencing an act of piracy. Not that I care, anyway...
  163.  
  164. 4. What are the keys used in VGB?
  165.   VGB Unix/X keys:
  166.  
  167.   [SPACE] - A button
  168.   [LALT]  - B button                        ([CONTROL] in Windows)
  169.   [TAB]   - SELECT button
  170.   [ENTER] - START button
  171.   [ESC]   - Quit emulation
  172.   [F1]    - Turn tracing on/off             (Not implemented in Windows)
  173.   [F2]    - Show LCD controller registers   (Not implemented in Windows)
  174.  
  175. 5. Where is the complete list of command line options of VGB?
  176.   Use -help option. It will tell VGB to display all options available in 
  177. your version. Following are the options available in VGB-Unix/X:
  178.  
  179.   -verbose <level>    - Select debugging messages [5]
  180.                         0 - Silent           1 - Startup messages
  181.                         2 - Illegal writes   4 - Illegal CPU ops
  182.                         8 - Bank switching
  183.   -vperiod <period>   - Set VBlank interrupts period [10000ops]
  184.   -uperiod <period>   - Number of interrupts per screen update [2]
  185.   -help               - Print this help page
  186.   -cheat <GG code>    - Activate a GameGenie cheat [not supported yet]
  187.   -shm/-noshm         - Use/don't use MIT SHM extensions for X [-shm]
  188.   -trap <address>     - Trap execution when PC reaches address [FFFFh]
  189.   -delay/nodelay      - Delay/don't delay coincidence int-s [-nodelay]
  190.   -saver/-nosaver     - Save/don't save CPU when inactive [-saver]
  191.   -color0 <name>      - Change color#0 [black]
  192.   -color1 <name>      - Change color#1 [#585858]
  193.   -color2 <name>      - Change color#2 [#989898]
  194.   -color3 <name>      - Change color#3 [white]
  195.  
  196. 6. Why some games do not run with VGB?
  197.   As it was said before, VGB emulation is not completely accurate yet.
  198. Also, some games will probably never run on VGB.
  199.  
  200. o If a game refuses to work, try changing -vperiod value from 2000 to
  201.   15000, or moving a "VBlank Period" knob in the VGB-Windows setup
  202.   window.
  203. o If you see a group of "dirty" lines on VGB screen, or a game behaves
  204.   strangely, try -delay/-nodelay options, or check/clear the "Delay
  205.   Line Interrupts" checkbox in the VGB-Windows setup window. 
  206. o If some sprites blink or do not appear at all, try changing -uperiod
  207.   value from 1 to 10 [1 will give you the best picture, but the slowest
  208.   emulation], or moving an "Update Period" knob in the VGB-Windows
  209.   setup window.
  210.  
  211. 7. Palette controls in VGB-Windows do not work.
  212.   This probably means that you are running Windows in the 256-color
  213. mode. In this mode, not all of 256 possible colors are available, and
  214. you will be able to choose only from the available colors. Switch
  215. Windows into 16-bit or 24-bit graphics and palette will start working.
  216.  
  217. 8. I start VGB-WIndows, but it tells me that WING.DLL is not found.
  218.   This means that you haven't installed WinG library necessary to run
  219. VGB. Check the information in the beginning of this manual on how to
  220. obtain WinG.
  221.  
  222. 9. I start VGB-WIndows, but it tells me that BWCC32.DLL is not found.
  223.   VGB-Windows comes with a file called BWCC32.DLL. This file should
  224. be either kept in the directory from which VGB runs, or put into
  225. \WINDOWS\SYSTEM directory.
  226.  
  227. 10. Why is VGB so slow on my computer?
  228.   Because your computer is too slow to run VGB. VGB is written entirely in
  229. C language and therefore is quite slow. Although it works on 486/33 and even 
  230. 386/33 PCs, it runs best on a Pentium/90 or a DEC Alpha/150. You can try to 
  231. speed it up by increasing -uperiod value controlling the number of vertical
  232. blanking impulses between screen updates to 3-6, and by decreasing -vperiod
  233. value controlling the number of CPU cycles between vertical blanking
  234. impulses to 3000-6000. Please, DO NOT SEND ME MAIL about VGB speed.
  235.  
  236. 11. Can I compile VGB with my Borland/Turbo C compiler?
  237.   You can, given that your compiler creates executables using flat 32bit 
  238. memory model. Two PC compilers which do that are WATCOM [using DOS4GW DOS 
  239. extender] and GCC [using DJPP extender]. The only Borland/Turbo C 32-bit 
  240. compiler that I'm aware of is for Windows.
  241.  
  242. 12. When compiling VGB under Unix, I get "undefined name" errors.
  243.   This means that your linker can not find the libraries necessary
  244. for VGB [namely, libX11.a and libXext.a]. Find these libraries in
  245. your system and modify the Makefile so that the final invocation
  246. of the C compiler has "-L<path_to_libs>" options. If the errors
  247. persist, try #undefining MITSHM option.
  248.  
  249. 13. When starting VGB-Unix/X, I get X_ShmAttach error.
  250.   You are probably trying to run VGB on a remote Xterminal while it 
  251. attempts to use shared memory for interfacing with X. Use -noshm option 
  252. to tell VGB not to use shared memory.
  253.  
  254. 14. VGB starts under Unix, but then I get X_PutImage error.
  255.   Unix/X version of VGB currently needs 256-color X. Neither 2-color 
  256. nor TrueColor Xterminals will work with the drivers included into 
  257. "official" VGB distribution.
  258.  
  259. 15. I start VGB-Unix/X but the window stays black.
  260.   Some other X application took over all available colors so that VGB 
  261. could not allocate any for itself. Check if you run XV, Netscape, or 
  262. something similar.
  263.  
  264. ---------------
  265. Marat Fayzullin
  266.  
  267.  
  268.  
  269.  
  270.  
  271. ******* changes in the Amiga version *******
  272.  
  273. - recompiled with SAS/C V6.30
  274. - requires OS 3.0 and 68020 minimum
  275. - key assignments changed, press "help" for an info requester
  276. - does not support a filename on the commandline, instead an ASL
  277.   filerequester is used
  278. - tested on: A4000/040, CV64 (playable)
  279.              A2000/030, ECS  (sloooooooowwww!)
  280.  
  281. History:
  282. V0.2 : first port of the X11 version. Not optimized in any way
  283. V0.3 : applied changes of the X11 V0.3, still no Amiga optimization
  284.        (assembler-coded graphics conversion is being worked on...)
  285. V0.31: Implemented some basic sound functions using audio.device
  286.        Sound does still not work though because we don't know the meaning
  287.        of all sound registers [unreleased]
  288. V0.32: Added tooltype: DoubleSize/S, makes the display twice as big.
  289.        [Released only on BBSs]
  290. V0.33: Got rid of the GimmeZeroZero-window. Some minor optimizations.
  291.        Bugfix: the DoubleSize extra image buffer wasn't freed on exit 8(
  292.        [Released only on BBSs]
  293.  
  294. To do:
  295. - speed up graphics
  296.   We took the graphics routines straight from the X11 version which uses
  297.   256-color chunky bitmaps. Speed is quite decent on a 4000/040 with
  298.   chunky-mode graphics board but unusable on ECS. Rewriting the display
  299.   format conversions should give a *big* speedup here.
  300. - implement sound. We're working on this. As soon as someone is able to
  301.   explain all the sound registers to us the code can be finished.
  302. - better user interface, maybe some GadTools stuff. NO, we will NOT use MUI
  303.   for this one :)
  304. - support for the CD32 joypad (an ordinary joystick doesn't have enough
  305.   buttons). Soon to come.
  306. - real disassembler and hex editor with save function ("freezer")
  307.  
  308. Not really:
  309. - contrast/brightness control
  310. - 4-player support (serial cable emu) via AmiTCP sockets
  311. - battery LED emulation
  312.  
  313.  
  314. If you have any suggestions or ideas for future versions, contact us at
  315. these email addresses:
  316. Matthias Bethke: Matthias.Bethke@sowi.uni-giessen.de
  317. Michael Boese  : skywalker@sweetdreams.lahn.de
  318.  
  319. ...or on the following boards:
  320. ThunderDome  (+49-6408-3249)
  321. Sweet Dreams (+49-6406-76571)
  322.